home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / lisp / wgdb-42.lha / wgdb-4.2 / bfd / syms.c < prev    next >
C/C++ Source or Header  |  1992-09-11  |  11KB  |  373 lines
  1. /* Generic symbol-table support for the BFD library.
  2.    Copyright (C) 1990-1991 Free Software Foundation, Inc.
  3.    Written by Cygnus Support.
  4.  
  5. This file is part of BFD, the Binary File Descriptor library.
  6.  
  7. This program is free software; you can redistribute it and/or modify
  8. it under the terms of the GNU General Public License as published by
  9. the Free Software Foundation; either version 2 of the License, or
  10. (at your option) any later version.
  11.  
  12. This program is distributed in the hope that it will be useful,
  13. but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15. GNU General Public License for more details.
  16.  
  17. You should have received a copy of the GNU General Public License
  18. along with this program; if not, write to the Free Software
  19. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
  20.  
  21. /*doc*
  22. @section Symbols
  23. BFD trys to maintain as much symbol information as it can when it
  24. moves information from file to file. BFD passes information to
  25. applications though the @code{asymbol} structure. When the application
  26. requests the symbol table, BFD reads the table in the native form and
  27. translates parts of it into the internal format. To maintain more than
  28. the infomation passed to applications some targets keep
  29. some information 'behind the sceans', in a structure only the
  30. particular back end knows about. For example, the coff back end keeps
  31. the original symbol table structure as well as the canonical structure
  32. when a BFD is read in. On output, the coff back end can reconstruct
  33. the output symbol table so that no information is lost, even
  34. information unique to coff which BFD doesn't know or understand. If a
  35. coff symbol table was read, but was written through an a.out back end,
  36. all the coff specific information would be lost. (.. until BFD 2 :).
  37.  
  38. The symbol table of a BFD is not necessarily read in until a
  39. canonicalize request is made. Then the BFD back end fills in a table
  40. provided by the application with pointers to the canonical
  41. information.
  42.  
  43. To output symbols, the application provides BFD with a table of
  44. pointers to pointers to @code{asymbol}s. This allows applications like
  45. the linker to output a symbol as read, since the 'behind the sceens'
  46. information will be still available.
  47.  
  48. @menu
  49. * Reading Symbols::
  50. * Writing Symbols::
  51. * typedef asymbol::
  52. * symbol handling functions::
  53. @end menu
  54.  
  55. @node Reading Symbols, Writing Symbols, Symbols, Symbols
  56. @subsection Reading Symbols
  57. There are two stages to reading a symbol table from a BFD; allocating
  58. storage, and the actual reading process. This is an excerpt from an
  59. appliction which reads the symbol table:
  60.  
  61. *+
  62.   unsigned int storage_needed;
  63.   asymbol **symbol_table;
  64.   unsigned int number_of_symbols;
  65.   unsigned int i;
  66.  
  67.   storage_needed = get_symtab_upper_bound (abfd);
  68.  
  69.   if (storage_needed == 0) {
  70.      return ;
  71.   }
  72.   symbol_table = (asymbol **) malloc (storage_needed);
  73.     ...
  74.   number_of_symbols = 
  75.      bfd_canonicalize_symtab (abfd, symbol_table); 
  76.  
  77.   for (i = 0; i < number_of_symbols; i++) {
  78.      process_symbol (symbol_table[i]);
  79.   }
  80. *-
  81.  
  82. All storage for the symbols themselves is in an obstack connected to
  83. the BFD, and is freed when the BFD is closed.
  84.  
  85. @node Writing Symbols, typedef asymbol, Reading Symbols, Symbols
  86. @subsection Writing Symbols
  87. Writing of a symbol table is automatic when a BFD open for writing
  88. is closed. The application attaches a vector of pointers to pointers to symbols
  89. to the BFD being written, and fills in the symbol count. The close and
  90. cleanup code reads through the table provided and performs all the
  91. necessary operations. The outputing code must always be provided with
  92. an 'owned' symbol; one which has come from another BFD, or one which
  93. has been created using @code{bfd_make_empty_symbol}. 
  94.  
  95. An example showing the creation of a symbol table with only one
  96. element:
  97.  
  98. *+
  99. #include "bfd.h"
  100. main() 
  101. {
  102.   bfd *abfd;
  103.   asymbol *ptrs[2];
  104.   asymbol *new;
  105.  
  106.   abfd = bfd_openw("foo","a.out-sunos-big");
  107.   bfd_set_format(abfd, bfd_object);
  108.   new = bfd_make_empty_symbol(abfd);
  109.   new->name = "dummy_symbol";
  110.   new->section = (asection *)0;
  111.   new->flags = BSF_ABSOLUTE | BSF_GLOBAL;
  112.   new->value = 0x12345;
  113.  
  114.   ptrs[0] = new;
  115.   ptrs[1] = (asymbol *)0;
  116.   
  117.   bfd_set_symtab(abfd, ptrs, 1);
  118.   bfd_close(abfd);
  119. }
  120.  
  121. ./makesym 
  122. nm foo
  123. 00012345 A dummy_symbol
  124.  
  125.  
  126. *-
  127.  
  128. Many formats cannot represent arbitary symbol information; for
  129. instance the @code{a.out} object format does not allow an arbitary
  130. number of sections. A symbol pointing to a section which is not one of
  131. @code{.text}, @code{.data} or @code{.bss} cannot be described.
  132. */
  133.  
  134.  
  135. /*doc*
  136. @node typedef asymbol, symbol handling functions, Writing Symbols, Symbols
  137.  
  138. */
  139. /*proto*
  140. @subsection typedef asymbol
  141. An @code{asymbol} has the form:
  142.  
  143. *+++
  144.  
  145. $typedef struct symbol_cache_entry 
  146. ${
  147. A pointer to the BFD which owns the symbol. This information is
  148. necessary so that a back end can work out what additional (invisible to
  149. the application writer) information is carried with the symbol. 
  150.  
  151. $  struct _bfd *the_bfd;
  152.  
  153. The text of the symbol. The name is left alone, and not copied - the
  154. application may not alter it. 
  155.  
  156. $   CONST char *name;
  157.  
  158. The value of the symbol.
  159.  
  160. $   symvalue value;
  161.  
  162. Attributes of a symbol:
  163.  
  164. $#define BSF_NO_FLAGS    0x00
  165.  
  166. The symbol has local scope; @code{static} in @code{C}. The value is
  167. the offset into the section of the data.
  168.  
  169. $#define BSF_LOCAL    0x01
  170.  
  171. The symbol has global scope; initialized data in @code{C}. The value
  172. is the offset into the section of the data.
  173.  
  174. $#define BSF_GLOBAL    0x02
  175.  
  176. Obsolete
  177.  
  178. $#define BSF_IMPORT    0x04
  179.  
  180. The symbol has global scope, and is exported. The value is the offset
  181. into the section of the data.
  182.  
  183. $#define BSF_EXPORT    0x08
  184.  
  185. The symbol is undefined. @code{extern} in @code{C}. The value has no meaning.
  186.  
  187. $#define BSF_UNDEFINED    0x10    
  188.  
  189. The symbol is common, initialized to zero; default in @code{C}. The
  190. value is the size of the object in bytes.
  191.  
  192. $#define BSF_FORT_COMM    0x20    
  193.  
  194. A normal @code{C} symbol would be one of:
  195. @code{BSF_LOCAL}, @code{BSF_FORT_COMM},  @code{BSF_UNDEFINED} or @code{BSF_EXPORT|BSD_GLOBAL}
  196.  
  197. The symbol is a debugging record. The value has an arbitary meaning.
  198.  
  199. $#define BSF_DEBUGGING    0x40
  200.  
  201. The symbol has no section attached, any value is the actual value and
  202. is not a relative offset to a section.
  203.  
  204. $#define BSF_ABSOLUTE    0x80
  205.  
  206. Used by the linker
  207.  
  208. $#define BSF_KEEP        0x10000
  209. $#define BSF_KEEP_G      0x80000
  210.  
  211. Unused
  212.  
  213. $#define BSF_WEAK        0x100000
  214. $#define BSF_CTOR        0x200000 
  215. $#define BSF_FAKE        0x400000 
  216.  
  217. The symbol used to be a common symbol, but now it is allocated.
  218.  
  219. $#define BSF_OLD_COMMON  0x800000  
  220.  
  221. The default value for common data.
  222.  
  223. $#define BFD_FORT_COMM_DEFAULT_VALUE 0
  224.  
  225. In some files the type of a symbol sometimes alters its location
  226. in an output file - ie in coff a @code{ISFCN} symbol which is also @code{C_EXT}
  227. symbol appears where it was declared and not at the end of a section. 
  228. This bit is set by the target BFD part to convey this information. 
  229.  
  230. $#define BSF_NOT_AT_END    0x40000
  231.  
  232. Signal that the symbol is the label of constructor section.
  233.  
  234. $#define BSF_CONSTRUCTOR   0x1000000
  235.  
  236. Signal that the symbol is a warning symbol. If the symbol is a warning
  237. symbol, then the value field (I know this is tacky) will point to the
  238. asymbol which when referenced will cause the warning.
  239.  
  240. $#define BSF_WARNING       0x2000000
  241.  
  242. Signal that the symbol is indirect. The value of the symbol is a
  243. pointer to an undefined asymbol which contains the name to use
  244. instead.
  245.  
  246. $#define BSF_INDIRECT     0x4000000
  247.  
  248. $  flagword flags;
  249.  
  250. A pointer to the section to which this symbol is relative, or 0 if the
  251. symbol is absolute or undefined. Note that it is not sufficient to set
  252. this location to 0 to mark a symbol as absolute - the flag
  253. @code{BSF_ABSOLUTE} must be set also.
  254.  
  255. $  struct sec *section;
  256.  
  257. Back end special data. This is being phased out in favour of making
  258. this a union.
  259.  
  260. $  PTR udata;    
  261. $} asymbol;
  262. *---
  263.  
  264. */
  265.  
  266. #include "bfd.h"
  267. #include "sysdep.h"
  268. #include "libbfd.h"
  269.  
  270. /*doc*
  271. @node symbol handling functions,  , typedef asymbol, Symbols
  272. @subsection Symbol Handling Functions
  273.  
  274. */
  275.  
  276. /*proto* get_symtab_upper_bound
  277. Returns the number of bytes required in a vector of pointers to
  278. @code{asymbols} for all the symbols in the supplied BFD, including a
  279. terminal NULL pointer. If there are no symbols in the BFD, then 0 is
  280. returned.
  281. *+
  282. #define get_symtab_upper_bound(abfd) \
  283.      BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
  284. *-
  285.  
  286. */
  287.  
  288. /*proto* bfd_canonicalize_symtab
  289. Supplied a BFD and a pointer to an uninitialized vector of pointers.
  290. This reads in the symbols from the BFD, and fills in the table with
  291. pointers to the symbols, and a trailing NULL. The routine returns the
  292. actual number of symbol pointers not including the NULL.
  293.  
  294. *+
  295. #define bfd_canonicalize_symtab(abfd, location) \
  296.      BFD_SEND (abfd, _bfd_canonicalize_symtab,\
  297.                   (abfd, location))
  298.  
  299. *-
  300. */
  301.  
  302.  
  303. /*proto* bfd_set_symtab
  304. Provided a table of pointers to to symbols and a count, writes to the
  305. output BFD the symbols when closed.
  306.  
  307. *; PROTO(boolean, bfd_set_symtab, (bfd *, asymbol **, unsigned int ));
  308. */
  309.  
  310. boolean
  311. bfd_set_symtab (abfd, location, symcount)
  312.      bfd *abfd;
  313.      asymbol **location;
  314.      unsigned int symcount;
  315. {
  316.   if ((abfd->format != bfd_object) || (bfd_read_p (abfd))) {
  317.     bfd_error = invalid_operation;
  318.     return false;
  319.   }
  320.  
  321.   bfd_get_outsymbols (abfd) = location;
  322.   bfd_get_symcount (abfd) = symcount;
  323.   return true;
  324. }
  325.  
  326. /*proto* bfd_print_symbol_vandf
  327. Prints the value and flags of the symbol supplied to the stream file.
  328.  
  329. *; PROTO(void, bfd_print_symbol_vandf, (PTR file, asymbol *symbol));
  330. */
  331. void
  332. DEFUN(bfd_print_symbol_vandf,(file, symbol),
  333. PTR file AND
  334. asymbol *symbol)
  335. {
  336.   flagword type = symbol->flags;
  337.   if (symbol->section != (asection *)NULL)
  338.       {
  339.     fprintf_vma(file, symbol->value+symbol->section->vma);
  340.       }
  341.   else 
  342.       {
  343.     fprintf_vma(file, symbol->value);
  344.       }
  345.   fprintf(file," %c%c%c%c%c%c%c%c%c%c",
  346.       (type & BSF_LOCAL)  ? 'l':' ',
  347.       (type & BSF_GLOBAL) ? 'g' : ' ',
  348.       (type & BSF_IMPORT) ? 'i' : ' ',
  349.       (type & BSF_EXPORT) ? 'e' : ' ',
  350.       (type & BSF_UNDEFINED) ? 'u' : ' ',
  351.       (type & BSF_FORT_COMM) ? 'c' : ' ',
  352.       (type & BSF_CONSTRUCTOR) ? 'C' : ' ',
  353.       (type & BSF_WARNING) ? 'W' : ' ',
  354.       (type & BSF_INDIRECT) ? 'I' : ' ',
  355.       (type & BSF_DEBUGGING) ? 'd' :' ');
  356.  
  357. }
  358.  
  359.  
  360. /*proto*  bfd_make_empty_symbol
  361. This function creates a new @code{asymbol} structure for the BFD, and
  362. returns a pointer to it.
  363.  
  364. This routine is necessary, since each back end has private information
  365. surrounding the @code{asymbol}. Building your own @code{asymbol} and
  366. pointing to it will not create the private information, and will cause
  367. problems later on.
  368. *+
  369. #define bfd_make_empty_symbol(abfd) \
  370.      BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
  371. *-
  372. */
  373.